The section describes the programming interface of the SAI Peripheral driver. More...

Data Structures
struct	sai_user_config_t
	The description structure for the SAI TX/RX module. More...

struct	sai_data_format_t
	Defines the PCM data format. More...

struct	sai_handler_t
	The SAI handler structure. More...

Macros
#define	USEDMA 1
	Use DMA mode or interrupt mode. More...

Typedefs
typedef void(*	sai_callback_t )(void *parameter)
	SAI callback function.

Enumerations
enum	sai_status_t { kStatus_SAI_Success = 0U, kStatus_SAI_Fail = 1U, kStatus_SAI_DeviceBusy = 2U }
	Status structure for SAI.

Functions
sai_status_t	sai_init (sai_handler_t handler, sai_user_config_t config)
	Initializes the SAI module. More...

sai_status_t	sai_deinit (sai_handler_t *handler)
	De-initializes the SAI module. More...

sai_status_t	sai_configure_data_format (sai_handler_t handler, sai_data_format_t format)
	Configures the PCM data format. More...

void	sai_start_read_data (sai_handler_t *handler)
	Starts reading data from FIFO. More...

void	sai_start_write_data (sai_handler_t *handler)
	Starts writing data to FIFO. More...

static void	sai_stop_read_data (sai_handler_t *handler)
	Stops reading data from FIFO, mainly to disable the DMA or the interrupt request bit. More...

static void	sai_stop_write_data (sai_handler_t *handler)
	Stop write data to FIFO, mainly to disable the DMA or the interrupt request bit. More...

static void	sai_clear_tx_status (sai_handler_t *handler)
	Clears the TX FIFO error flag. More...

static void	sai_clear_rx_status (sai_handler_t *handler)
	Clears the RX FIFO error flag. More...

static uint32_t *	sai_get_fifo_address (sai_handler_t *handler)
	Gets the FIFO address of the data channel. More...

uint32_t	sai_send_data (sai_handler_t handler, uint8_t addr, uint32_t len)
	Sends a certain length data. More...

uint32_t	sai_receive_data (sai_handler_t handler, uint8_t addr, uint32_t len)
	Receives a certain length data. More...

void	sai_register_callback (sai_handler_t handler, sai_callback_t callback, void callback_param)
	Registers the callback function after a transfer. More...

SAI Driver

Overview

The SAI driver initializes, configures, starts, and stop SAI. The SAI driver implements functions of configure, send and receive data.

Initialization

To initialize SAI, call the sai_init() function and pass the parameters needed. The parameter is the sai_handler_t structure and SAI configuration structure. The function opens the clock gate and initializes the SAI modules according to the structure information.

Configure

Configure is implemented by the sai_configure_data_format() function. To use this function, the users should transfer the audio data format to the SAI module.

Call diagram

To use the SAI driver, follow these steps:

Initialize the SAI module by calling the sai_init() function.
Configure the audio data features of SAI by calling the sai_configure_data_foramt() function.
Send/receive data by calling the sai_send_data() or the sai_receive_data() functions.
Start TX or RX by calling the sai_start_write_data() or the sai_start_read_data() function.
Shut down the SAI module by calling the sai_deinit() function.

This is example code to initialize and configure the SAI driver in the DMA mode:

// Initialize handler structure.
sai_handler_t handler;
handler.direction = AUDIO_TX;
handler.instance = 0;
handler.fifo_channel = 0;
//Initialize config structure.
sai_config_t tx_config;
tx_config.bus_type = kSaiBusI2SLeft;
tx_config.channel = 0;
tx_config.slave_master = kSaiMaster;
tx_config.sync_mode = kSaiModeAsync;
tx_config.bclk_source = kSaiBclkSourceMclkDiv;
tx_config.mclk_source = kSaiMclkSourceSysclk;
tx_config.mclk_divide_enable = true;
//Data format of audio data
audio_data_format_t format;
format.bits = 16;
format.sample_rate = 44100;
format.mclk = 384 * format->sample_rate;
format.words = 2;
format.watermark = 4;
sai_init(&handler, &tx_config);
sai_configure_data_format(&handler,format);
//option: register callback functions for finished transfer
sai_register_callback(&handler, callback, NULL);
//start send data
sai_send_data(&handler, addr, len);

Data Structure Documentation

struct sai_user_config_t

Data Fields
sai_mclk_source_t	mclk_source
	Master clock source. More...

bool	mclk_divide_enable
	Enable the divide of master clock to generate bit clock. More...

sai_sync_mode_t	sync_mode
	Synchronous or asynchronous. More...

sai_bus_t	bus_type
	I2S left, I2S right or I2S type. More...

sai_master_slave_t	slave_master
	Master or slave. More...

sai_bclk_source_t	bclk_source
	Bit clock from master clock or other modules. More...

uint8_t	channel
	Which FIFO is used to transfer. More...

Field Documentation

sai_mclk_source_t sai_user_config_t::mclk_source

bool sai_user_config_t::mclk_divide_enable

sai_sync_mode_t sai_user_config_t::sync_mode

sai_bus_t sai_user_config_t::bus_type

sai_master_slave_t sai_user_config_t::slave_master

sai_bclk_source_t sai_user_config_t::bclk_source

uint8_t sai_user_config_t::channel

struct sai_data_format_t

Data Fields
uint32_t	sample_rate
	Sample rate of the PCM file.

uint32_t	mclk
	Master clock frequency.

uint8_t	bits
	How many bits in a word.

uint8_t	words
	How many word in a frame.

uint8_t	watermark
	When to send interrupt/DMA request.

struct sai_handler_t

The structure is used in the SAI runtime.

Data Fields
uint8_t	instance
	SAI instance.

bool	direction
	RX or TX.

uint8_t	fifo_channel
	Which data channel is used.

Macro Definition Documentation

#define USEDMA 1

Function Documentation

sai_status_t sai_init	(	sai_handler_t *	handler,
		sai_user_config_t *	config
	)

This function initializes the SAI registers according to the configuration structure. This function initializes the basic settings for SAI, including some board relevant settings. Notice: This function does not initialize an entire SAI instance. This function only initializes the TX or RX according to the value in the handler.

Parameters

handler	SAI handler structure pointer.
config	The configuration structure of SAI.

Returns: Return kStatus_SAI_Success while the initialize success and kStatus_SAI_Fail if failed.

sai_status_t sai_deinit ( sai_handler_t * handler )

This function closes the SAI device. It does not close the entire SAI instance. It only closes the TX or RX according to the value in the handler.

Parameters

handler SAI handler structure pointer of the SAI module.

Returns: Return kStatus_SAI_Success while the process success and kStatus_SAI_Fail if failed.

sai_status_t sai_configure_data_format	(	sai_handler_t *	handler,
		sai_data_format_t *	format
	)

The function mainly configures an audio sample rate, data bits and a channel number.

Parameters

handler	SAI handler structure pointer of the SAI module.
format	PCM data format structure pointer.

Returns: Return kStatus_SAI_Success while the process success and kStatus_SAI_Fail if failed.

void sai_start_read_data ( sai_handler_t * handler )

The function enables the interrupt/DMA request source and enables the transmit channel.

Parameters

handler SAI handler structure pointer of the SAI module.

void sai_start_write_data ( sai_handler_t * handler )

The function enables the interrupt/DMA request source and enables the receive channel.

Parameters

handler SAI handler structure pointer of the SAI module.

static void sai_stop_read_data ( sai_handler_t * handler )

inlinestatic

This function provides the method to pause receiving data.

Parameters

handler SAI handler structure pointer of the SAI module.

static void sai_stop_write_data ( sai_handler_t * handler )

inlinestatic

This function provides the method to pause writing data.

Parameters

handler SAI handler structure pointer of the SAI module.

static void sai_clear_tx_status ( sai_handler_t * handler )

inlinestatic

Parameters

handler SAI handler structure pointer of the SAI module.

static void sai_clear_rx_status ( sai_handler_t * handler )

inlinestatic

Parameters

handler SAI handler structure pointer of the SAI module.

static uint32_t* sai_get_fifo_address ( sai_handler_t * handler )

inlinestatic

This function is mainly used for the DMA settings, which the DMA configuration needs for the source/destination address of SAI.

Parameters

handler SAI handler structure pointer of the SAI module.

Returns: Returns the address of the data channel FIFO.

uint32_t sai_send_data	(	sai_handler_t *	handler,
		uint8_t *	addr,
		uint32_t	len
	)

This function sends the data to the TX FIFO. This function starts the transfer, and while finishing the transfer, it calls the callback function registered by users.

Parameters

handler	SAI handler structure pointer of the SAI module.
addr	Address of the data which needs to be transferred.
len	The data length which need to be sent.

Returns: Returns the length which was sent.

uint32_t sai_receive_data	(	sai_handler_t *	handler,
		uint8_t *	addr,
		uint32_t	len
	)

This function receives the data from the RX FIFO. This function starts the transfer, and while finishing the transfer, it calls the callback function registered by users.

Parameters

handler	SAI handler structure pointer of the SAI module.
addr	Address of the data which needs to be transferred.
len	The data length which needs to be received.

Returns: Returns the length received.

void sai_register_callback	(	sai_handler_t *	handler,
		sai_callback_t	callback,
		void *	callback_param
	)

This function tells SAI which function needs to be called after a period length transfer.

Parameters

handler	SAI handler structure pointer of the SAI module.
callback	Callback function defined by users.
callback_param	The parameter of the callback function.

Data Structures

Macros

Typedefs

Enumerations

Functions

SAI Driver

Overview

Initialization

Configure

Call diagram

Data Structure Documentation

Data Fields

Field Documentation

Data Fields

Data Fields

Macro Definition Documentation

Function Documentation